home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.060 < prev    next >
Encoding:
Text File  |  1991-01-11  |  9.0 KB  |  193 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIgs
  8. #60:    Menu Manager Memorabilia
  9.  
  10. Revised by:    Matt Deatherage, Dave Lyons, & Tim Swihart       November 1990
  11. Written by:    Dave Lyons                                           July 1989
  12.  
  13. This Technical Note discusses the Menu Manager, specifically a few anomalies
  14. and some tips for making menus your friends.
  15. Changes since May 1990:  Noted that System Software 5.0.3 fixes a bug in
  16. NewMenuBar2.
  17. _____________________________________________________________________________
  18.  
  19.  
  20. The Menu Manager Is Your Friend
  21.  
  22. In general, this is the truth.  You can do all kinds of nifty things with
  23. menus, especially in System Software 5.0 and later.  However, there are a few
  24. things you should know unless you generally are fond of pain in your life.
  25.  
  26.  
  27. Disabling Menus Gracefully
  28.  
  29. As documented, SetMenuFlag can be used to disable and enable entire menus.
  30. When a menu is disabled, the menu title and all items within the menu are
  31. disabled.  You may pull down a disabled menu, but you may not select any item
  32. within it (unless the routine MenuGlobal has been used to allow inactive menu
  33. items to be selected).
  34.  
  35. Volume 1 of the Apple IIgs Toolbox Reference says you should call DrawMenuBar
  36. if you change the appearance of a menu title with SetMenuFlag.  You can do
  37. this; this is fine.  It may, however, induce dizziness if used often.
  38.  
  39. A more graceful way to dim menus is to follow SetMenuFlag with HiliteMenu.
  40. Calling HiliteMenu causes the menu title to be redrawn to reflect the current
  41. (or new) highlighting and menu flags.  Using HiliteMenu instead of DrawMenuBar
  42. allows you to disable and enable menus gracefully, without noticeable flicker
  43. or threat of nasty patent infringement lawsuits from strobe light
  44. manufacturers.
  45.  
  46.  
  47. "System" Bars Versus "Window" Bars
  48.  
  49. As far as the Menu Manager is concerned, there are only two kinds of menu bars.
  50. One kind is in a window and the other kind is not.  The former are called
  51. "window" menu bars and the latter are generally referred to as "system" menu
  52. bars.
  53.  
  54. Most people think of the System bar as the big menu bar across the top of the
  55. screen.  This is encouraged by calls like SetSysBar, which takes a menu bar
  56. handle and sets the menu bar across the top of the screen to that menu bar.
  57. Trying to rename one or the other of these two concepts at this point is
  58. probably useless; instead, this Note refers to the bar across the top of the
  59. screen as the "System" bar (with a capital S), and menu bars not in windows as
  60. "system" bars (with a lowercase s).
  61.  
  62. When you start the Menu Manager, it creates an empty System bar for you.
  63. Before System Software 5.0, most people simply called NewMenu and InsertMenu to
  64. insert menus into that System bar.  All was well in the world.
  65.  
  66. When 5.0 was released, it became very easy to create a new menu bar and all the
  67. menus within it using the NewMenuBar2 call.  This avoids a lot of code, and
  68. many new people use it.  The problem comes with DrawMenuBar.  If you simply
  69. call NewMenuBar2 to obtain your menu bar and menus from resources, then call
  70. DrawMenuBar to make them visible, you usually get an empty menu bar.  Why?  The
  71. windowPtr parameter passed to NewMenuBar2 determines whether or not the new
  72. menu bar created is a system bar or a window bar-it does not force the new bar
  73. to be the System (note the capital 'S') bar.  So when DrawMenuBar draws the
  74. current System bar, it hasn't changed from the empty default one created by
  75. MenuStartUp.
  76.  
  77. This is why Volume 3 of Apple IIgs Toolbox Reference recommends code similar to
  78. the following:
  79.  
  80.        menuHandle := NewMenuBar2(refDesc,menuBarTRef,NIL);
  81.        SetSysBar(menuHandle);
  82.        SetMenuBar(NIL);       {NIL makes the System bar the current menu bar}
  83.  
  84. if you want your menu bar to be the one across the top of the screen.
  85.  
  86.  
  87. A Bug in NewMenuBar2
  88.  
  89. NewMenuBar2 is a handy thing to have around, but it does have a problem in
  90. 5.0.2 and earlier.  When the Menu Manager is done with resources, it tries to
  91. use the internal toolbox call CMReleaseResource to free them in memory.
  92. However, it passes the wrong resource ID, and CMReleaseResource calls
  93. SysFailMgr if it encounters any errors at all (such as Specified resource not
  94. found).
  95.  
  96. What NewMenuBar2 does improperly is push the high word of the resource ID onto
  97. the stack twice, instead of the high word followed by the low word.  Because of
  98. the way the Resource Manager operates, CMReleaseResource returns with no error
  99. if the ID passed is NIL, but the resource is not released (another good reason
  100. not to try to use the illegal value NIL as a resource ID).
  101.  
  102. If the high word of the menu bar resource is $0000, NewMenuBar2 passes a
  103. resource ID of NIL to CMReleaseResource, which then doesn't quite release the
  104. resource, but returns no error.  The menu bar resource hangs around in memory
  105. until ResourceShutDown.  It's usually fairly small, so this is no loss.  It
  106. still takes up less room than menu strings, which had to stay in memory until
  107. MenuShutDown.
  108.  
  109. If the high word of the menu bar resource is not zero, the bug causes
  110. CMReleaseResource to bring down the system.  When using System Software 5.0.2
  111. or earlier, make sure all menu bar resource IDs have a high word of $0000.
  112. System Software 5.0.3 fixes this bug.
  113.  
  114.  
  115. Menu and Menu Title ID Numbers
  116.  
  117. Table 13-4 in Volume 1 of Apple IIgs Toolbox Reference gives a listing of menu
  118. and menu item ID numbers.  In both lists, $0000 and $FFFF are "reserved for
  119. internal use" and noted that $0000 usually indicates the first menu in the bar
  120. (or first item in the menu) and $FFFF usually indicates the last menu in the
  121. bar (or last item in the menu).  Some developers have taken this to mean that
  122. they should give their first menu an ID of $0000 and their last one an ID of
  123. $FFFF.
  124.  
  125. This assumption is incorrect..  The Menu Manager may change these values
  126. internally to reflect such IDs, but they must not be assigned that way by an
  127. application.  Some applications that use IDs of $0000 or $FFFF break under
  128. System Software 5.0 and later.  Note that $0000 can be used as the insertAfter
  129. parameter to InsertMenu to insert a menu at the left of a menu bar, but $FFFF
  130. is not a valid insertAfter value.
  131.  
  132.  
  133. Desk Accessories and Menus
  134.  
  135. Some desk accessory developers would like to have their NDAs insert a menu in
  136. the System menu bar.  While the menu itself can be inserted, the NDA cannot
  137. detect that a user has selected an item within that menu.  The application gets
  138. the event and does not know what to do with it.  NDAs that need a menu can put
  139. a menu bar in their own window.  Since the mouseDown event then happens within
  140. the NDA's window, the NDA gets the event and can handle it normally.  Be sure
  141. to make the NDA's menu bar the current menu bar before calling MenuSelect from
  142. within your NDA (to avoid possible conflicts between NDA menu item IDs and
  143. application menu item IDs).  Restore the current menu bar to the application's
  144. menu bar before returning control to the application.  Failure to do so
  145. prevents the application from finding its menus.  Apple IIgs Technical Note #3,
  146. Window Information Bar Use documents how to put a menu in a window's
  147. information bar.
  148.  
  149.  
  150. Documentation Error in MenuSelect
  151.  
  152. Volume 1 of Apple IIgs Toolbox Reference states that MenuSelect returns the
  153. menu ID and the item ID of the selected item in the when field of the event
  154. record.  This is incorrect.  MenuSelect actually returns the information in the
  155. wmTaskData field of the task record (and this, in fact, is why you pass a task
  156. record and not just an event record to MenuSelect).
  157.  
  158.  
  159. Menu Strings and Bank Boundaries
  160.  
  161. NewMenu takes a pointer to a string; this string must not cross a bank
  162. boundary.  If it does, a menu containing random garbage may result.
  163.  
  164. If your NewMenu strings are contained in your code segments, everything is
  165. fine-code segments cannot cross bank boundaries.  Depending on your development
  166. environment, strings that are not in a code segment may or may not be allowed
  167. to cross bank boundaries.  If you can find no other way to guarantee the
  168. strings do not cross a bank boundary, use NewHandle to allocate blocks with
  169. attributes $4010 (fixed, no bank cross) and copy the strings to these blocks.
  170.  
  171. If you create menus from resources, be sure the resources have their
  172. noCrossBank attribute bits set.  Note that a memory block that can cross a bank
  173. boundary usually does not, so your application may be working by accident.
  174.  
  175. Note that this restriction applies only to menu strings, not the menu templates
  176. that can be used with NewMenu2.
  177.  
  178.  
  179. Return Values From GetMenuTitle and GetMItem
  180.  
  181. Starting with System Software 5.0, GetMenuTitle and GetMItem can return handles
  182. and resource IDs, not just pointers.  The type of data returned depends on how
  183. the menu or item was created, so existing applications are not affected.  For
  184. more information, see Apple IIgs Toolbox Reference, Volume 3, Chapter 37, "New
  185. Features of the Menu Manager."
  186.  
  187.  
  188. Further Reference
  189. _____________________________________________________________________________
  190.   o  Apple IIgs Toolbox Reference, Volumes 1 & 3
  191.   o  Apple IIgs Technical Note #3, Window Information Bar Use
  192.  
  193.